home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / Pascal / Code Resources / Eclectic CDEFs / CDEF Utilities / StubCDEF Folder / StubCDEF Info next >
Text File  |  1997-03-06  |  4KB  |  62 lines
  1. StubCDEF
  2. ========
  3. Copyright © Sebastiano Pilla 1996
  4. All rights reserved
  5. Original Pascal source code Copyright © by Peter N. Lewis
  6.  
  7.  
  8.  
  9. General Informations
  10. --------------------
  11. The StubCDEF control definition function enables debugging of 'CDEF' resources at the source level.
  12.  
  13.  
  14. Contents of the StubCDEF folder
  15. -------------------------------
  16. - StubCDEF Info: the documentation file you are reading now.
  17. - StubCDEF.p: Pascal source code for the StubCDEF 'CDEF' resource.
  18. - StubCDEF.rsrc: ResEdit file with the compiled code of the StubCDEF resource.
  19. - StubCDEF.π: THINK Pascal project for compiling the StubCDEF resource.
  20. - StubCDEFIntf.p: Pascal source code for automating the preflight and postflight operations required by the StubCDEF mechanism.
  21.  
  22.  
  23. How to use the StubCDEF CDEF
  24. ----------------------------
  25. Include the StubCDEF resource (found inside the StubCDEF.rsrc file) in your test project.
  26.  
  27. In your resource templates use the StubCDEF resource ID (factory preset at 128) as the CDEF ID in the calculation of the procID field, like:
  28.  
  29.     procID := (16 * StubCDEF res. ID) + variation code
  30.  
  31. Then, after loading a control from a resource file, plug the 'real' control definition procedure into the refCon field of the control, like:
  32.  
  33.     ctrlDefUPP := NewControlDefProc(inControlDefProcPtr);
  34.     SetControlReference(myControlHdl, SInt32(ctrlDefUPP));
  35.  
  36. This task is automated for you by the InstallRealCDEFUPP or the AttachRealCDEFUPP routines in the StubCDEFIntf.p file.
  37.  
  38. The StubCDEF stub works by retrieving the real control defproc from the control's refCon and then calling it. Unfortunately, you lose the ability to use the control refCon for other purposes; this is compensated by the ability of debugging your CDEF at the source level.
  39.  
  40. Moreover, disposing of the control without disposing of its ctrlDefUPP may cause memory leaks; see below for the solution implemented in the StubCDEFIntf.p file.
  41.  
  42.  
  43. Note
  44. ----
  45. There are two problems with this approach: the initCntl and dispCntl messages aren't handled by your 'real' control defproc.
  46.  
  47. The Control Manager sends the initCntl just after it creates a control; unfortunately, at this time the only defproc active is the StubCDEF, which simply doesn't yet know how to respond. This means that all the initialization and data allocation needed by the real defproc couldn't theoretically be done.
  48.  
  49. In addition, when an application call DisposeControl (or any other Toolbox routine that disposes of some control) the Control Manager sends the dispCntl message to the control defproc: if you dispose of the 'real' defproc before disposing of the control, then the defproc cannot deallocate all the memory it requested at initialization time.
  50.  
  51. The solutions to these problems are in the StubCDEFIntf.p file.
  52.  
  53. The InstallRealCDEFUPP loads a control template with GetNewControl, installs the 'real' defproc into the control refCon, then calls it explicitly with the initCntl message, like:
  54.  
  55.     result := CallControlDefProc(GetControlVariant(outControlHdl), outControlHdl, initCntl, 0, ctrlDefUPP);
  56.  
  57. The AttachRealCDEFUPP performs the same function, but with an already created control.
  58.  
  59. The RemoveRealCDEFUPP solves the memory leaking problem with the dispCntl message. Before calling DisposeControl (or any other Toolbox routine that disposes of your control) call RemoveRealCDEFUPP to deallocate any storage you may have allocated at initialization and to dispose of the real defproc UPP. This is done by calling explicitly the real defproc with the dispCntl message, like:
  60.  
  61.     result := CallControlDefProc(GetControlVariant(inControlHdl), inControlHdl, dispCntl, 0, ctrlDefUPP);
  62.